\documentclass[11pt]{article}

\usepackage{misc-latex}

\mediummargins

\newcommand{\gsect}[1]{%
    \linespace{1}
    \noindent{\large\tb{#1}}\par
    \linespace{0.8}%
}

\newcommand{\T}[1]{\texttt{#1}}

\begin{document}
\thispagestyle{empty}

\begin{center}
\Large
Alloy GUI Hacking Guide\\
\small
Jesse Pavel, 2002\\
\end{center}

\linespace{1}

This guide presents some of the common tasks that a maintainer of the Alloy GUI
package may want to perform, and the changes in the various classes that would
be needed to effect them. For a higher-level overview of the architecture and a
diagram of dependencies, see the \T{alloygui.pdf} that should be in the same
place that this document is located.

As a general method of understanding the code, I recommend that one first read
the overview, and then, for a specific task, follow the flow of code that
results from a user event. To find out how AST synchronization works, for
instance, look for the class that listens for selection events on the AST,
and follow the trail of function calls from \T{LocatableTextArea} to
\T{LocDisplayer} to see what is happening behind the scenes. The below
descriptions will help as well.

\linespace{1}

\gsect{Component Layout}

The layout is managed in the constructor of \T{AlloyGUI}. Most of the
components (i.e. \T{ASTTree}) have a method that exports a Swing
JComponent which can be placed wherever one wishes.

\gsect{Menu Items}

Adding a menu item requires two changes in \T{AlloyGUI.java}: first,
create a new Action for the menu item, using the pattern of \T{getXAction};
then in the constructor, make a new \T{JMenuItem}, set its Action, and
add it to a menu.

\gsect{Solve/Build Procedures}

The control flow for any of the Build or Execute calls is as so: \T{AlloyGUI}
registers listeners for Build and Solve events with \T{AlloySolver}; when the
use compiles or solves, \T{AlloySolver} starts a new thread and performs the
computation, and then calls, in the Swing event thread, the listeners for the
events. In the listeners \T{AlloyGUI} sets the enabled state of the menu items
as is appropriate to the result of the build or solve.

\gsect{Tunneling in the AST}

All of the logic for tunneling is contained in \T{AlloyGUIASTHandler}. To
implement certain tunneling features, one might have to change
\T{SwingASTVisitor} to embed additional information in the AST when building
it, \T{NodeInfo} to provide a place to store additional information, and
\T{SwingASTRenderer}, to change the way that the AST is shown, for instance
if one wants to highlight pivot nodes.



\end{document}
